TABLE.OPEN Function
Syntax
<TBL> as P = Open(C tablename [,N table_open_mode[,C alias[,C encryption key]]])
<TBL> as P = Open(C tablename [,SQL::Arguments args[,C alias[,C encryption key]]])
Arguments
- tablename
The table file's path and name. The .DBF file extension is automatically added to the filename if you do not specify a file extension. To open a set, you must supply the .SET extension.
- table_open_mode
If the table is an active-link table and has arguments in the SQL Select statement, allows you to pass in argument values.
- alias
Optional. Determines the access privileges that apply to the open table file. You can use one of the following system variables:
- Variable
- Function
- FILE_RO_EXCLUSIVE
Read Only (Exclusive)
- FILE_RW_EXCLUSIVE
Read or Write (Exclusive)
- FILE_RO_SHARED
Read Only (Shared)
- FILE_RW_SHARED
Read or Write (Shared)
- FILE_REUSE_EXISTING
Intended for internal use only. Allows you to create another pointer to an open file.
- encryption
Optional. Specifies the alias that the table will have. By default, the table alias is automatically derived from the table name. For example, if the table name is "customer", the first instance of the table that is opened will have an alias of "customer", the second instance will have an alias of "customer0" and so on. It is rare that you would need to specify a specific alias for a table when opening it. If you specify a NULL Alias, Alpha Anywhere automatically computes the alias name.
- Arguments
Optional. Only needed if the table has been encrypted, and the default encryption key has not been set (using the DEFAULT_ENCRYPTION_KEY_SET() function), of if the table was encrypted using a different encryption key than the default encryption key.
Description
Open an existing table.
Discussion
The TABLE.OPEN() method opens an existing table or set, and creates an object pointer (<TBL>) that references the table, or in the case of a set, the parent table of the set. Note : If you have set a Master Password for your database, and have encrypted tables using the Tools > Security menu, then the default encryption key is automatically set when the database is opened, and you do not need to specify the Password parameter when opening tables. The TABLE.OPEN() method automatically finds and opens an associated index file (.cdx) matching the table name and its related data dictionary. Note : In addition to the above modes, another mode flag can be used in conjunction with the above modes. The flag, FILE_REUSE_EXISTING indicates to Alpha Anywhere that rather than opening a new instance of the table, it should attempt to find an already open instance of the table (if possible) and use that instead. For example, specify an Open Mode of FILE_REUSE_EXISTING + FILE_RW_SHARED, indicates that you want to get a pointer to an existing instance of a table in read/write/shared mode. The table opened by the TABLE.OPEN() method does not become the primary table of the session. For example, if a session is started by opening a form, the table for that form is the primary table in the session. The user interface menus and buttons on the form apply to the session's primary table. The table opened by the TABLE.OPEN() method can only be manipulated by Xbasic methods, not by the user interface. You can change the primary table of a session with the TABLE.RESET() method, however this method should only be used in the Interactive session. If you use the <TBL>.ENTER_BEGIN() or <TBL>.CHANGE_BEGIN() methods to do data entry into a table opened with the TABLE.OPEN() method, not all field rules are in effect. Engine level field rules, such as auto-increment, and validation expressions are enforced. However, user interface level field rules, such as Lookups and case conversion are not enforced. If you want all field rules to be enforced, you should open a form based on the table (you can use the FORM.LOAD() method to open the form invisibly) and then use form methods to enter data. The TABLE.CURRENT() method automatically assigns a unique alias to the table. To determine the alias for a particular pointer, use the <TBL>.NAME_GET() method. The alias is the table name, modified with a trailing "1", "2", "3", etc. if necessary, to ensure that the alias is unique. The <TBL>.OPEN() method will fail if you try to open a set, and any of the tables in the set are already open. This is because Alpha Anywhere assumes that the aliases for all of the tables in the set will be the same as the table names. If, however, one of the tables in the set is already open in the session, the table name will have already been assigned as the alias name to the open table. Refer to ((Contrasting TABLE.OPEN Functionwith TABLE.CURRENT Functionand TABLE.GET Function|Contrasting TABLE.OPEN()with TABLE.CURRENT()and TABLE.GET())). Use the <TBL>.FETCH_FIRST(), <TBL>.FETCH_LAST(), <TBL>.FETCH_FIND(), or <TBL>.FETCH_GOTO() methods to position the record pointer in the table after you first open it.
Example
This script opens the same table twice, and then a set. It then print out the alias for each table.
tbl_1 = table.open("d:\a5\a_sports\invoice.SET")
tbl_2 = table.open("d:\a5\a_sports\customer.dbf")
tbl_3 = table.open("d:\a5\a_sports\customer.dbf")
alias_1 = tbl_1.name_get()
trace.writeln("Alias for invoice.set is alias of parent table: " + alias_2)
alias_2 = tbl_2.name_get()
trace.writeln("Alias for first instance of customer: " + alias_1)
alias_3 = tbl_3.name_get()
trace.writeln("Alias for second instance of customer: " + alias_2)
tbl_1.close()
tbl_2.close()
tbl_3.close()This script opens a table and positions the record pointer at the first record in the table.
tbl = table.open("d:\a5\a_sports\customer.dbf")
tbl.fetch_first()This script is attached to a button on a form. The form is based on the Customer table. There is a variable on the form called what_customer. The user enters a value in this variable and the script searches for matching records.
dim shared what_customer as C
tbl = table.current()
query.filter = "customer = var->what_customer"
indx = tbl.query_create()
records = indx.records_get()
ui_msg_box("Notice", alltrimrecords? + "records were selected")
'Make the form show the records that were selected
parentform.resynch()This script is similar to the above script. It uses TABLE.OPEN()however, and so it has no effect on the records that are visible in the form. Note : Query.Filter is a text string.
dim shared what_customer as C
tbl = table.open("customer")
query.filter = "customer = var->what_customer"
indx = tbl.query_create()
records = indx.records_get()
ui_msg_box("Notice", alltrimrecords? + "records were selected")The following resynch()command has no effect. The form continues to display the same records it did before the query was run.
parentform.resynch() tbl.close()
Active Link Tables
When you open an active-link table, the SQL Select statement in the active-link table definition might include arguments. For example: Select * from customers where city = :whatcity If you don't provide values for the arguments, Alpha Anywhere will prompt for the values. The following example shows how you can provide argument values to the .Open() method:
dim args as sql::arguments
args.add("whatcity","London")
dim tbl as p
tbl = table.open("customer",args)See Also